home *** CD-ROM | disk | FTP | other *** search
/ TOS Silver 2000 / TOS Silver 2000.iso / Falcon / WHIP031 / VLMDOCU / VLMDOCU.TXT
Encoding:
Text File  |  1985-06-06  |  8.1 KB  |  198 lines
  1.  
  2. * FORMAT DESCRIPTION OF VLM FILES
  3.  
  4.     Basicly *.vlm files have the same format as the normal atari program
  5.     files. At the beginning of the text-segment there is the module 
  6.     structure, which looks like this:
  7.     
  8.       DC.B "VLM1"       ;vlm module type
  9.       DC.L infotext     ;pointer to an infotext
  10.       DC.L settings     ;pointer to a settings-structure
  11.       DC.L init         ;pointer to an initialization routine
  12.       DC.L deinit       ;pointer to an deinitialization routine
  13.       DC.L main         ;pointer to the mainloop routine
  14.       
  15.     If there is no infotext or a settings-structure, the value has to
  16.     be set to zero (DC.L 0). 
  17.     
  18.   + VLM MODULE TYPES
  19.     
  20.       The moduletype "VLM1" uses an own DSP program, which analysis the
  21.       incoming sound. The DSP initialisation must be done in the init
  22.       routine.
  23.       For easier implementations of effects there is a moduletype "VLM2".
  24.       This moduletype runs a standart DSP program. This DSP-program takes
  25.       out some information of the music. After every mainloop cycle these
  26.       values are transfered to an area of the cpu memory. 
  27.       
  28.   + INFOTEXT
  29.     
  30.       Every infotext line must be finished by zero. The infotext itself
  31.       must be finished by two zeros. So an infotext can look like this:
  32.       
  33.         infotext:
  34.         DC.B "Spectre analyser",0
  35.         DC.B "version: 1.0",0
  36.         DC.B "author:  Achim Settelmeier",0
  37.         DC.B 0
  38.         EVEN
  39.         
  40.       The number of characters per line is not limited but it is good
  41.       to use less lines than 25 because the width of the info-box of "Whip".
  42.       
  43.   + SETTINGS
  44.  
  45.       Every VLM module can feature parameters for more flexibility. In
  46.       general the number of parameters is not limited. The format of the
  47.       settings structure is for example:
  48.       
  49.         settings:
  50.         DC.L 3           ;number of parameters
  51.         DC.L par_name1   ;pointer to the name of parameter 1
  52.         DC.L 1           ;type of parameter 1 (activator)
  53.         DC.L 0           ;value of parameter 1 (initialised with defaultvalue)
  54.                          ;1=enabled, 0=disabled
  55.         DC.L 0           ;pointer to a parameter structure (depends of the
  56.                          ;type of parameter), 0=no parameter structure
  57.                          
  58.         DC.L par_name2   ;pointer to the name of parameter 2
  59.         DC.L 2           ;type of parameter 2 (choice)
  60.         DC.L 1           ;at the beginning the first button is enabled
  61.         DC.L par_struct2 ;pointer to choice parameter structure
  62.         
  63.         DC.L par_name3   ;pointer to the name of parameter 3
  64.         DC.L 3           ;type of parameter 3 (slider)
  65.         DC.L 100         ;defaultvalue of slider and later the slidervalue
  66.         DC.L par_struct3 ;pointer to slider parameter structure
  67.       
  68.       There are different kinds of parameter types:
  69.       
  70.     - ACTIVATOR
  71.         
  72.         An activator is just a button which can be selected or deselected.
  73.         It can either be active or not. There is no special parameter 
  74.         structure for this type of parameter. As parameter type must be
  75.         specified 1. The value of an activator can be 1 (enabled) or 0
  76.         (disabled).
  77.         
  78.     - CHOICE
  79.     
  80.         A choice is represented by a set of alternatives. Each alternative
  81.         is a button, but only one of them can be selected at one time. So
  82.         these are the same as radiobuttons. The parameter type must be set
  83.         to 2 for this one. The value of the parameter represents the number
  84.         of the selected alternatives (beginning with 1). For this parameter
  85.         an additional parameter structure is needed to be specified:
  86.         
  87.           par_struct2:
  88.           DC.L 3           ;number of alternatives
  89.           DC.B "SLOW",0    ;text of button 1
  90.           DC.B "MEDIUM",0  ;text of button 2
  91.           DC.B "FAST",0    ;text of button 3 
  92.     
  93.         Each button text must be terminated by zero.  
  94.         
  95.     - SLIDER
  96.     
  97.         A slider can be used to get a value in a specified range. A slider
  98.         has the following parameter structure
  99.      
  100.           par_struct3:
  101.           DC.L 0           ;minimum value
  102.           DC.L 200         ;maximum value
  103.           
  104.   + INIT ROUTINE
  105.       
  106.       The routine is called at first and offers the possibility to make
  107.       precalculations, set up values etc. This routine is called only once.
  108.       The init routine gets one parameter which is a pointer to a structure.
  109.       This structure features pointers to different service routines. It
  110.       is very useful to store the pointer to this service structure in a
  111.       variable (for example: move.l a0,service_struct).
  112.       
  113.     - SERVICE STRUCTURE
  114.     
  115.         The service structure is filled out by the calling program. The 
  116.         VLM module can feel free to make use these routines, which are:
  117.         
  118.         offset | routine
  119.         -----------------------------------------------------------------
  120.         00     | set_vblrout (a0: routine adress)
  121.                |   set a routine that will be called everytime when a
  122.                |   vbl interrupt occures. The routine has to end with rts
  123.         04     | wait_vbl
  124.                |   wait until vertical syncronisation (vbl occured)
  125.         08     | set_scradr (a0: new screen adress)
  126.                |   set adress of visible screen to the specified adress
  127.         12     | set_resolution (d0: resolution id)
  128.                |   set the screen resolution to the specified one
  129.         16     | get_left_spec
  130.                |   returns adress of the left spectre (which consists of 
  131.                |   128 words) in a0. Values ranges from 0 to 65535
  132.                |   This function is only usable in "VLM2" modules.
  133.         20     | get_right_spec
  134.                |   returns adress of the right spectre in a0.
  135.                |   This function is only usable in "VLM2" modules.
  136.         24     | get_left_volume
  137.                |   returns the value of the left input volume in d0
  138.                |   The value can be beetween 0 and 65535.
  139.                |   This function is only usable in "VLM2" modules.
  140.         28     | get_right_volume
  141.                |   returns the value of the right input volume in d0.
  142.                |   This function is only usable in "VLM2" modules.
  143.         32     | get_left_osci
  144.                |   returns adress of the left oscilloscope data
  145.                |   (256 words) in a0. Each value is 16bit signed.
  146.                |   This function is only usable in "VLM2" modules.
  147.         36     | get_right_osci
  148.                |   returns adress of the right oscilloscope data
  149.                |   This function is only usable in "VLM2" modules.
  150.  
  151.         The routines can destroy the registers d0,d1,d2,a0,a1. 
  152.  
  153.     - RESOLUTIONS
  154.         
  155.         It is possible to set a resolution using the service routine
  156.         set_resolution. Featured resolutions are:
  157.         1: 320x240 16 bit
  158.         2: 320x100 16 bit
  159.         3: 320x240  8 bit
  160.         4: 320x100  8 bit
  161.       
  162.   + MAIN ROUTINE
  163.   
  164.       This routine is called in every mainloop cycle and is the kernel of
  165.       the vlm module. The mainroutine must end with rts and does NOT include
  166.       the "mainloop". It is just a routine, which is a part of the mainloop.
  167.       The mainloop control is made by the calling program.
  168.     
  169. * GENERAL RULES
  170.  
  171.   Please do only use the functions provided by the module interface. Please
  172.   do not use any GEMDOS, XBIOS etc. functions, except when you code a VLM1
  173.   module and want to initalize the DSP. 
  174.   The whole vlm module is executed in supervisor mode. Please do not change 
  175.   the cpu mode in your own module.
  176.   
  177.   
  178. * CONTACT
  179.  
  180.   Norman Feske
  181.   Uhlandstr.6
  182.   01069 Dresden
  183.   phone: ++49(351)471 68 75
  184.   email: nf2@inf.tu-dresden.de
  185.   www:    http://escape.atari.org
  186.   
  187. * LAST WORDS
  188.  
  189.   I would be very happy to see your creations. It was nice to collect all 
  190.   existing vlm modules on my homepage. So everyone had an overview about
  191.   all modules.
  192.  
  193.   If you have any problems just contact me.
  194.   
  195.   Good luck,
  196.   
  197. Norman Feske (NO/Escape)
  198.